home *** CD-ROM | disk | FTP | other *** search
/ Windows Expert / Windows Expert.iso / windownt / resfmt.zip / RESFMT.TXT < prev   
Text File  |  1992-11-02  |  44KB  |  1,053 lines
  1. Win32 Binary resource formats.
  2.  
  3.  
  4.  
  5. 0.  Preface.
  6. This document was edited and released by Microsoft Developer Support.
  7. It describes the binary format of resources in Win32.  The
  8. information is provided at this point because we feel it would make
  9. the work of application development easier.  Unfortunately, the
  10. information in this document may change before the final release of
  11. Windows/NT.  Microsoft is NOT committing to stay with these formats
  12. by releasing this document.  Questions or followups for any of the
  13. information presented here should be posted to Compuserve MSWIN32
  14. forum, section 4.    -Steve Firebaugh
  15.  
  16.  
  17.  
  18. 1. Overview
  19. This document details the structure of the resource binary file
  20. (.res) format for Windows NT and DOS Windows 32.  The structure is
  21. similar to the existing Windows 16 (Win 3.0/3.1) structure, but
  22. supports essential new features such as UNICODE strings, version
  23. headers, and DWORD alignment.  To support these changes, the file
  24. written by the resource compiler must be changed from Windows 16.
  25.  
  26. 1.1 Comparison between Windows 3.0/3.1 and Windows 32
  27. The Windows 16 resource file is a file containing one or more binary
  28. resources.  Each resource is preceded by a variable length structure
  29. containing:  Type, Name, Flags, Size.  The Type and Name fields are
  30. either a string identifying the Type or Name, or a WORD value
  31. specifying the ordinal identity of the resource.  The Flags field
  32. specifies to the system how to load into memory the resource, and the
  33. size specifies the size in bytes of the resource.  The size,
  34. therefore, points to the next resource in the file.
  35.  
  36. The Windows 32 (both NT and DOS) resource file retains this
  37. structure, while expanding the header information with several
  38. additional values.  It also adds a few fields to some of the pre-
  39. defined resources (Menu and Dialog, for instance), aligns all fields
  40. within the predefined resources on WORD or DWORD boundaries, and adds
  41. UNICODE (16-bit character) support to the data structures.
  42.  
  43. One additional difference in resource files for Windows 32 is worth
  44. noting.  This does not directly affect the structure of the resource
  45. file, but is rather a difference in how resource files are handled
  46. and incorporated into an executable image (dll or exe).  Windows NT
  47. uses Coff format objects.  Because of this, and the fact that the
  48. Windows 32 exe format is much different than the Windows 16 format,
  49. the PDK provides a utility named CVTRES that converts a resource file
  50. into a Coff object.  The linker then incorporates this object
  51. directly into the resulting executable image.  No provision is made
  52. (as in Windows 16) for running the second pass of the resource
  53. compiler multiple times to update the resources:  relinking the image
  54. is required.
  55.  
  56. However, the Windows 32 API provides a set of APIs that allow a
  57. program to enumerate all resources within an executable image, and
  58. update individual resources in the image.
  59.  
  60. 1.2 Strings in UNICODE
  61.  
  62. All strings in a resource file are now stored in UNICODE format.  In
  63. this format, all characters are represented by a 16-bit (WORD) value.
  64. The first 256 characters are identical to the 256 characters in the
  65. Windows ANSI character set (although the characters are represented
  66. by 16 bits each rather than 8bits).  This means that they are
  67. terminated with a UNICODE_NULL symbol rather than a single NULL.  The
  68. resource compiler translates all normal ASCII strings into UNICODE by
  69. calling the MultiByteToWideChar function provided by the Windows API.
  70. All escaped characters are stored directly, and are assumed to be
  71. valid UNICODE characters for the resource.  If these strings are read
  72. in later by an application as ASCII (for instance, by calling the
  73. LoadString api), they will be converted back from UNICODE to ASCII
  74. transparently by the loader.
  75.  
  76. The only exception to the rule is strings in RCDATA statements.
  77. These psuedo-strings are not real strings, but merely a convenient
  78. notation for a collection of bytes.  Users may overlay a structure
  79. over the data from an RCDATA statement, and expect certain data to be
  80. at certain offsets.  If a psuedo-string gets automatically changed
  81. into a UNICODE string, it would inadvertently change the offsets of
  82. things in the structure and break those applications.  Hence, these
  83. psuedo-strings must be left as ASCII bytes.  To specify a UNICODE
  84. string inside an RCDATA statement, the user should use the explicit L-
  85. quoted string.
  86.  
  87. 1.3 DWORD Alignment
  88.  
  89. To make resource binary files easier to read under Windows 32, all
  90. objects within the file are to be DWORD aligned.  This includes
  91. headers, as well as data entries.  This does not usually entail
  92. changes in the order of the fields of resource data structures, but
  93. does entail the need for some padding between fields.
  94.  
  95. The single exception to this rule is the font and fontdir structures.
  96. The reason for the exception is that these two structures are copied
  97. directly from other files, and are not used by RC.
  98.  
  99. 2.  General information
  100.  
  101. The resource file is created by the resource compiler (RC) while
  102. parsing the resource script file (.RC) and including any other
  103. resource data files (eg. .ICO, .CUR, .BMP, .FNT).  The resource file
  104. contains all information necessary to build the resource table in the
  105. executable image.  The main purpose of the resource file is to speed
  106. the edit-compile-link cycle by not always forcing resources to be
  107. recompiled.
  108.  
  109. There are currently about a dozen pre-defined resource types.  These
  110. include Menus, Dialogs, Accelerators, Strings, Icons, Cursors,
  111. Bitmaps, Fonts and Version.  These resources are used by the Windows
  112. system to define the appearance of the application window.  The
  113. resource script allows the application writer to represent these
  114. features in an easily editable form.  Other type ranges are reserved
  115. for use by the application for application-specific data.  No attempt
  116. is made by the resource compiler to modify this user-defined data
  117. from 16-bit to 32-bit format.
  118.  
  119. The executable image file for Windows 32 is not a Segmented image.
  120. In the 16-bit executable image file, each resource was placed into a
  121. separate segment in the image file.  The Windows 32 image file places
  122. all resources into a single Object or section.  The Windows 32 image
  123. file also provides a binary-sorted resource table that allows fast
  124. lookup of a particular resource, rather than a table that must be
  125. searched linearly, as in the 16-bit image file.  Because this Windows
  126. 32 image file format is more complex that the Windows 16 format,
  127. making it harder to update directly, the Windows 32 API provides
  128. methods of modifying the resource data directly.
  129.  
  130. The CVTRES conversion utility that converts the resource file into a
  131. coff object creates the resource table.  This table contains two or
  132. three directories, indexed by Type, Name and Language, in that order.
  133. The Language directory is optional.  The Type and Name directories
  134. consist of two parts:  the part dedicated to resources whose types or
  135. names are represented by strings, and those represented by ordinal
  136. WORD values.  Because the use of strings as resource type and name
  137. identifiers takes considerably more room than ordinal identifiers,
  138. Microsoft recommends that they not be used.
  139.  
  140. Note that, as all strings in a resource file (including the strings
  141. used to identify the type and name of resources) are UNICODE, the
  142. corresponding strings in the program that are being passed to
  143. LoadBitmap, etc., must also be UNICODE (only if the application is
  144. using the UNICODE set of apis rather than the ASCII set).  This is
  145. facilitated by use of the TEXT macro provided in winnt.h.
  146.  
  147. The third level, language, provides the capability for the
  148. application developer to ship a single executable image that supports
  149. more than one language.  For instance, one image providing French,
  150. French-Canadian and French-Belgium could be easily shipped in one
  151. image file.  An application could also be shipped with support for
  152. all languages supported by the UNICODE standard, although this would
  153. probably make the image very large.
  154.  
  155. 2.1 New statements
  156.  
  157. Several new statements have been added that the Windows 32 resource
  158. compiler processes.
  159.  
  160. 2.1.1 New Button statements.
  161.  
  162. These statements allow the application developer the same freedom of
  163. expression that the PUSHBUTTON, DEFPUSHBUTTON, etc., statements do,
  164. and correspond to the appropriate button style.
  165.  
  166. They all have syntax identical to that of PUSHBUTTON, etc.
  167.  
  168. 2.1.1.1 AUTO3STATE
  169.  
  170. Allows declaration of an AUTO3STATE button.
  171.  
  172. 2.1.1.2 AUTOCHECKBOX
  173.  
  174. Allows declaration of an AUTOCHECKBOX button.
  175.  
  176. 2.1.1.3 AUTORADIOBUTTON
  177.  
  178. Allows declaration of an AUTORADIOBUTTON button.
  179.  
  180. 2.1.1.5 PUSHBOX
  181.  
  182. Allows declaration of a PUSHBOX button.
  183.  
  184. 2.1.1.6 STATE3
  185.  
  186. Allows declaration of a 3STATE button (the 3 is at the end for syntax
  187. purposes).
  188.  
  189. 2.1.1.7 USERBUTTON
  190.  
  191. Allows declaration of a USERBUTTON user-defined button.
  192.  
  193. 2.1.2 EXSTYLE statement
  194.  
  195. This statement allows the application developer to designate one of
  196. the extended (WS_EX_xxx) styles for a dialog or control window.
  197. There are three methods, depending upon what is needed.
  198.  
  199. It may be placed just below the DIALOG statement to apply to the
  200. dialog window (like the CAPTION or STYLE statements).
  201.  
  202.      EXSTYLE <flags>
  203.      
  204. It may be placed on the DIALOG statement with the memory flags.
  205.  
  206.      FOOBAR DIALOG [MemFlags...] [EXSTYLE=<flags>] x, y, dx, dy
  207.      
  208. It may also be placed on the individual CONTROL, PUSHBUTTON, LTEXT,
  209. etc. statements at the end of the statement.
  210.  
  211.      AUTOCHECKBOX "autocheckbox", id, x, y, dx, dy
  212.      [styleflags][exstyleflags]
  213.      
  214. 2.1.3 CHARACTERISTICS statement
  215.  
  216. This statement allows the application developer to specify
  217. information about the resource that may be of use to tools that read
  218. and write resource files.  It has no significance to the system and
  219. is not stored in the image file.
  220.  
  221.      CHARACTERISTICS <user defined DWORD value>
  222.      
  223. 2.1.4 VERSION statement
  224.  
  225. This statement is intended to allow the application to specify a
  226. version number of the resource in the resource file (for those tools
  227. that read and write resource files.)  It has no significance to the
  228. system and is not stored in the image file.
  229.  
  230.      VERSION <user defined DWORD value>
  231.      
  232. 2.1.5 LANGUAGE statement
  233.  
  234. The LANGUAGE statement is used to specify the language the resource
  235. file, or section of resource file, is written in.  It may be placed
  236. anywhere within the resource script file that a single-line statement
  237. (such as ICON, CURSOR, BITMAP) may be placed.  The scope of the
  238. language specified by a LANGUAGE statement is from that point in the
  239. script file to the next LANGUAGE statement, or the end of the file.
  240.  
  241.      LANGUAGE <majornumber>,<minornumber>
  242.      
  243. where <majornumber> represents the language id, and <minornumber> the
  244. sub-language identifiers.  The values specified in winnls.h should be
  245. used.
  246.  
  247. The LANGUAGE statement may also be placed before the BEGIN statement
  248. for MENU, DIALOG, STRINGTABLE, ACCELERATOR and RCDATA resources,
  249. along with other optional statements like CAPTION, STYLE, etc.  If
  250. the statement is placed here, it's scope is limited to the resource
  251. being defined.
  252.  
  253. 2.1.6 MESSAGETABLE statement
  254.  
  255. The MESSAGETABLE statement is used to include a message table.  A
  256. message table is a special-purpose string table that is used to
  257. contain error or informational messages, and may contain formatting
  258. information.  The format is:
  259.  
  260.      <nameid> MESSAGETABLE <filename>
  261.      
  262. 3. Resource Header Format
  263.  
  264. The general format of the entire file is simply a number of resource
  265. file entries concatenated together.  Each resource contains the
  266. information about a single resource, such as a dialog or a string
  267. table.
  268.  
  269. Each entry consists of a resource header followed by the data for
  270. that resource.  A resource header (which is DWORD aligned) is
  271. composed of four elements: two dwords containing the size of the
  272. header and the size of the resource data, the resource type, the
  273. resource name, and additional resource information.  The data for the
  274. resource follows the resource header and is specific to each
  275. particular type of resource.
  276.  
  277. 3.1 DataSize
  278.  
  279. This field gives the size of the data that follows the header, not
  280. including any file padding between this resource and any resource
  281. that follows this resource in the resource file.
  282.  
  283. 3.2 HeaderSize
  284.  
  285. The HeaderSize field gives the size of the resource header structure
  286. that follows.
  287.  
  288. 3.3 Type
  289.  
  290. The type field can either be a number or a double-null-terminated
  291. UNICODE string specifying the name of the type.  This variable kind
  292. of type is known as a `Name or Ordinal' field, and is used in most
  293. places in a resource file where an ID may appear.
  294.  
  295. The first WORD of a Name or Ordinal field identifies whether the
  296. field is a number or a string.  If the first WORD is 0xffff (an
  297. invalid UNICODE character), then the following WORD of information is
  298. the type number.  Otherwise, the field is specified by a UNICODE
  299. string.
  300.  
  301. If the type field is a number, then the number specifies a standard
  302. or user-defined resource type.  All standard Windows resource types
  303. have been assigned numbers, which are listed below.  This list is
  304. taken from the header file used to make RC and contains the type
  305. number of the various resource types:
  306.  
  307.     /* Predefined resource types */
  308.     #define    RT_NEWRESOURCE      0x2000
  309.     #define    RT_ERROR            0x7fff
  310.     #define    RT_CURSOR           1
  311.     #define    RT_BITMAP           2
  312.     #define    RT_ICON             3
  313.     #define    RT_MENU             4
  314.     #define    RT_DIALOG           5
  315.     #define    RT_STRING           6
  316.     #define    RT_FONTDIR          7
  317.     #define    RT_FONT             8
  318.     #define    RT_ACCELERATORS     9
  319.     #define    RT_RCDATA           10
  320.     #define    RT_MESSAGETABLE     11
  321.     #define    RT_GROUP_CURSOR     12
  322.     #define    RT_GROUP_ICON       14
  323.     #define    RT_VERSION          16
  324.     #define    RT_NEWBITMAP        (RT_BITMAP|RT_NEWRESOURCE)
  325.     #define    RT_NEWMENU          (RT_MENU|RT_NEWRESOURCE)
  326.     #define    RT_NEWDIALOG        (RT_DIALOG|RT_NEWRESOURCE)
  327.     
  328. If the type field is a string, then the type is a user-defined type.
  329.  
  330. 3.4 Names
  331.  
  332. A name identifies the particular resource.  A name (like a type) may
  333. be a number or a string, and they are distinguished in the same way
  334. as numbers and strings are distinguished in the type field.
  335.  
  336. Note that no padding (for DWORD alignment) is needed between the Type
  337. and Name fields, as they contain only WORD data and hence the Name
  338. field will always be properly aligned.  However, there may need to be
  339. a WORD of padding after the Name field to align the rest of the
  340. header on DWORD boundaries.
  341.  
  342. 3.5 Additional Header Information
  343.  
  344. The additional information contains more information about the
  345. particular resource data, including size and language ID.  The
  346. structure of the Header, plus it's additional information is as
  347. follows:
  348.  
  349. struct tagResource {
  350.   DWORD  DataSize;           // size of data without header
  351.   DWORD  HeaderSize;         // Length of the additional header
  352.   [Ordinal or name TYPE]     // type identifier, id or string
  353.   [Ordinal or name NAME]     // name identifier, id or string
  354.   DWORD  DataVersion;        // predefined resource data version
  355.   WORD   MemoryFlags;        // state of the resource
  356.   WORD   LanguageId;         // UNICODE support for NLS
  357.   DWORD  Version;            // Version of the resource data
  358.   DWORD  Characteristics;    // Characteristics of the data
  359.   } ;
  360.     
  361. The additional information structure will always begin on a DWORD
  362. boundary within the resource file, which may require adding some
  363. padding in between the name field and the ResAdditional structure.
  364.  
  365. 3.5.1 DataVersion
  366.  
  367. The version determines which version of the data within the resource
  368. data that follows.  This may be used in the future to allow
  369. additional information to be entered into the predefined formats.
  370.  
  371. 3.5.2 MemoryFlags
  372.  
  373. The field wMemoryFlags contains flags telling the state of a given
  374. resource.  These attributes are given to a given resource by
  375. modifiers in the .RC script.  The script identifiers inject the
  376. following flag values:
  377.  
  378.     #define    MOVEABLE            0x0010
  379.     #define    FIXED               ~MOVEABLE
  380.     #define    PURE                0x0020
  381.     #define    IMPURE              ~PURE
  382.     #define    PRELOAD             0x0040
  383.     #define    LOADONCALL          ~PRELOAD
  384.     #define    DISCARDABLE         0x1000
  385.     
  386. The resource compiler for NT always ignores the setting of the
  387. MOVEABLE, IMPURE, and PRELOAD flags.
  388.  
  389. 3.5.3 LanguageId
  390.  
  391. The language ID is included in each resource to specify the language
  392. that the strings are written with when they need to be translated
  393. back to a single byte strings.  As well, there may be multiple
  394. resources of exactly the same type and name which differ in only the
  395. language of the strings within the resources.
  396.  
  397. The language IDs are documented in Appendix A of the NLS
  398. specification, or in winnls.h.  The language of a resource or set of
  399. resources is specified by the LANGUAGE statement.
  400.  
  401. 3.5.4 Version and Characteristics
  402.  
  403. Currently, there is space in the resource file format for version and
  404. characteristic information of the resource.  These values can be set
  405. by the resource compiler by using the VERSION or CHARACTERISTICS
  406. statements.
  407.  
  408. 3.6 Differentiating 16 and 32-bit resource files.
  409.  
  410. Because it might be desirable for an ISV's tool that reads and writes
  411. resource files to be able to read either the older Windows 16 format
  412. files and the new Windows 32 format, Microsoft has devised a method
  413. to do this using illegal type and name ordinal numbers.
  414.  
  415. The method involved is to place an illegal resource in the resource
  416. file.  The following eight bytes were chosen:
  417.  
  418.      0x00 0x00 0x00 0x00 0x20 0x00 0x00 0x00
  419.      
  420. Assume that it is a 16-bit file.  In that case, the Type is illegal
  421. since the first 0x00 says string, but a zero-length string is an
  422. illegal string.  This, then is an illegal 16-bit resource header,
  423. indicating that the file is a 32-bit file.
  424.  
  425. Assume that it is a 32-bit file.  Given that, the size of the data is
  426. zero, which surely will never be the case.
  427.  
  428. The Windows 32 resource compiler prefaces each 32-bit resource file
  429. with this string of data (followed by an additional data structure
  430. describing a zero-length resource with 0 ordinal type and 0 ordinal
  431. name), allowing differentiation of 16 and 32-bit resource files.  Any
  432. tools reading resource files should ignore this resource.
  433.  
  434. 3.7 File Alignment.
  435.  
  436. Because it is sometimes useful to separate resources into several
  437. scripts and then concatenate them after compiling the resource files
  438. separatly, it is necessary to specify that resource files are padded
  439. to a dword size.  If this padding were not included, it could result
  440. in the first resource of the second and/or subsequent resource files
  441. not aligning upon a dword boundary.
  442.  
  443. 4.  Resource Data Format
  444.  
  445. For any of the pre-defined data types, all structures are DWORD
  446. aligned, including the bitmap, icon, and font header structures.  As
  447. well, the data will always begin on a DWORD boundary.
  448.  
  449. 4.1 Version Resources
  450.  
  451. Version resources are used to record the version of the application
  452. using the resource file.  Version resources contain a fixed amount of
  453. information.  The structure of the version resource is as follows:
  454.  
  455. typedef struct tagVS_FIXEDFILEINFO {
  456.   DWORD  dwSignature;        // e.g.  0xfeef04bd
  457.   DWORD  dwStrucVersion;     // e.g.  0x00000042 = "0.42"
  458.   DWORD  dwFileVersionMS;    // e.g.  0x00030075 = "3.75"
  459.   DWORD  dwFileVersionLS;    // e.g.  0x00000031 = "0.31"
  460.   DWORD  dwProductVersionMS; // e.g.  0x00030010 = "3.10"
  461.   DWORD  dwProductVersionLS; // e.g.  0x00000031 = "0.31"
  462.   DWORD  dwFileFlagsMask;    // = 0x3F for version "0.42"
  463.   DWORD  dwFileFlags;        // e.g.  VFF_DEBUG | VFF_PRERELEASE
  464.   DWORD  dwFileOS;           // e.g.  VOS_DOS_WINDOWS16
  465.   DWORD  dwFileType;         // e.g.  VFT_DRIVER
  466.   DWORD  dwFileSubtype;      // e.g.  VFT2_DRV_KEYBOARD
  467.   DWORD  dwFileDateMS;       // e.g.  0
  468.   DWORD  dwFileDateLS;       // e.g.  0
  469.   } VS_FIXEDFILEINFO;
  470.  
  471. 4.2 Icon Resources
  472.  
  473. The ICON statement in the .RC script does not create a single
  474. resource object, but creates a group of resources.  This allows
  475. Windows programs a degree of device-independence through the use of
  476. different pixel bitmaps on hardware configurations with differing
  477. capabilities.  Icons, most often designed for differing numbers of
  478. pixel planes and pixel counts, are grouped and treated by Windows as
  479. a single resource.  In the .RES and .EXE files, however, they are
  480. stored as a group of resources.  These groups are stored in a .RES
  481. file with the components first (in this case the different icons
  482. [type 3]) and a group header following (Type 14).  The group header
  483. contains the information necessary to allow Windows to select the
  484. proper icon to display.
  485.  
  486. The components have the following structure:
  487.  
  488.         [Resource header (type = 3)]
  489.     
  490.         [DIB Header]
  491.         [Color DIBits of icon XOR mask]
  492.         [Monochrome DIBits of AND mask]
  493.     
  494. Each component is given an ordinal ID that is unique from all other
  495. icon components.
  496.  
  497. The Device Independent Bitmap (DIB) header's fields represent the
  498. masks' information separately with two exceptions.  First, the height
  499. field represents both the XOR and AND masks.  Before converting the
  500. two DIBs to Device Dependent Bitmaps (DDB), the height should be
  501. divided by two.  The masks are always the same size and are one-half
  502. the size given in the DIB header.  Second, the number of bits per
  503. pixel and bit count refer to the XOR mask.  The AND mask is always
  504. monochrome and should be interpreted as having one plane and one bit
  505. per pixel.  Before using an icon with Windows refer to the SDK
  506. reference materials for more information on DIBs.  Since the format
  507. of an icon component closely resembles the format of the .ICO file,
  508. the documentation in section 9.2 of the Windows SDK Reference is
  509. useful.  DDBs should not be used for Windows 32 applications.
  510.  
  511. The group header is described here:
  512.  
  513.     [Resource header (type = 14)]
  514.     
  515. struct IconHeader {
  516.   WORD   wReserved;          // Currently zero
  517.   WORD   wType;              // 1 for icons
  518.   WORD   wCount;             // Number of components
  519.   WORD   padding;            // filler for DWORD alignment
  520.   };
  521.   
  522. The next portion is repeated for each component resource:
  523.  
  524. struct ResourceDirectory {
  525.   BYTE   bWidth;
  526.   BYTE   bHeight;
  527.   BYTE   bColorCount;
  528.   BYTE   bReserved;
  529.   WORD   wPlanes;
  530.   WORD   wBitCount;
  531.   DWORD  lBytesInRes;
  532.   WORD   wNameOrdinal;       // Points to component
  533.   WORD   padding;            // filler for DWORD alignment
  534.   };
  535.     
  536. Notice that the group header consists of a fixed header and data that
  537. repeats for each group component.  Both of these parts are fixed
  538. length allowing for random access of the group component information.
  539.  
  540. This group header contains all of the data from the .ICO header and
  541. from the individual resource descriptors.
  542.  
  543. 4.3 Menu Resources
  544.  
  545. Menu resources are composed of a menu header followed by a sequential
  546. list of menu items.  There are two types of menu items:  popups and
  547. normal menu items.  The MENUITEM SEPARATOR is a special case of a
  548. normal menu item with an empty name, zero ID, and zero flags.  The
  549. format for these types is shown here:
  550.  
  551.     [Resource header (type = 4)]
  552.     
  553. struct MenuHeader {
  554.   WORD   wVersion;           // Currently zero
  555.   WORD   cbHeaderSize;       // Also zero
  556.   };
  557.     
  558. These next items are repeated for every menu item.
  559.  
  560. Popup menu items (signalled by fItemFlags & POPUP):
  561.  
  562. struct PopupMenuItem {
  563.   WORD   fItemFlags;
  564.   WCHAR  szItemText[];
  565.   };
  566.     
  567. Normal menu items (signalled by !(fItemFlags & POPUP)):
  568.  
  569. struct NormalMenuItem {
  570.   WORD   fItemFlags;
  571.   WORD   wMenuID;
  572.   WCHAR  szItemText[];
  573.   };
  574.     
  575. The wVersion and cbHeaderSize structure members identify the version
  576. of the menu template.  They are both zero for Windows 3.0 but may be
  577. incremented with future changes to the menu template.
  578.  
  579. The WORD fItemFlags is a set of flags describing the menu item.  If
  580. the POPUP bit is set, the item is a POPUP.  Otherwise, it is a normal
  581. menu component.  There are several other flag bits that may be set.
  582. Their values are as follows:
  583.  
  584.     #define    GRAYED         0x0001   // 'GRAYED' keyword
  585.     #define    INACTIVE       0x0002   // 'INACTIVE' keyword
  586.     #define    BITMAP         0x0004   // 'BITMAP' keyword
  587.     #define    OWNERDRAW      0x0100   // 'OWNERDRAW' keyword
  588.     #define    CHECKED        0x0008   // 'CHECKED' keyword
  589.     #define    POPUP          0x0010   // Used internally
  590.     #define    MENUBARBREAK   0x0020   // 'MENUBARBREAK' keyword
  591.     #define    MENUBREAK      0x0040   // 'MENUBREAK' keyword
  592.     #define    ENDMENU        0x0080   // Used internally
  593.     
  594. The fItemFlags portion of the last menu item in a given POPUP is
  595. flagged by OR'ing it with ENDMENU.  It is important to note that
  596. since popups can be nested, there may be multiple levels of items
  597. with ENDMENU set.  When menus are nested, the items are inserted
  598. sequentially.  A program can traverse this hierarchy by checking for
  599. the item with the ENDMENU flag set.
  600.  
  601. 4.4 Dialog Box Resources
  602.  
  603. A dialog box is contained in a single resource and has a header and a
  604. portion repeated for each control in the dialog box.  The header is
  605. as follows:
  606.  
  607.     [Resource header (type = 5)]
  608.     
  609. struct DialogBoxHeader {
  610.   DWORD  lStyle;
  611.   DWORD  lExtendedStyle;     // new for NT
  612.   WORD   NumberOfItems;
  613.   WORD   x;
  614.   WORD   y;
  615.   WORD   cx;
  616.   WORD   cy;
  617.   [Name or Ordinal] MenuName;
  618.   [Name or Ordinal] ClassName;
  619.   WCHAR  szCaption[];
  620.   WORD   wPointSize;         // Only here if FONT set for dialog
  621.   WCHAR  szFontName[];       // This too
  622.   };
  623.   
  624. The item DWORD lStyle is a standard window style composed of flags
  625.   found in WINDOWS.H.    The default style for a dialog box is:
  626.   
  627.     WS_POPUP | WS_BORDER | WS_SYSMENU
  628.     
  629. The lExtendedStyle DWORD is used to specify the extended window style
  630. flags.  If an extended style is specified on the DIALOG statement, or
  631. with the other optional modifier statements, this DWORD is set to
  632. that value.
  633.  
  634. The items marked `Name or Ordinal' are the same format used
  635. throughout the resource file (most notably in each resource header)
  636. to store a name or an ordinal ID.  As before, if the first word is an
  637. 0xffff, the next two bytes contain an ordinal ID.  Otherwise, the
  638. first 1 or more WORDS contain a double-null-terminated string.  An
  639. empty string is represented by a single WORD zero in the first
  640. location.
  641.  
  642. The WORD wPointSize and WCHAR szFontName entries are present if the
  643. FONT statement was included for the dialog box.  This can be detected
  644. by checking the entry lStyle.  if lStyle & DS_SETFONT (DS_SETFONT =
  645. 0x40), then these entries will be present.
  646.  
  647. The data for each control starts on a DWORD boundary (which may
  648. require some padding from the previous control), and its format is as
  649. follows:
  650.  
  651. struct ControlData {
  652.   DWORD  lStyle;
  653.   DWORD  lExtendedStyle;
  654.   WORD   x;
  655.   WORD   y;
  656.   WORD   cx;
  657.   WORD   cy;
  658.   WORD   wId;
  659.   [Name or Ordinal] ClassId;
  660.   [Name or Ordinal] Text;
  661.   WORD   nExtraStuff;
  662.   };
  663.     
  664. As before, the item DWORD lStyle is a standard window style composed
  665. of the flags found in WINDOWS.H.  The type of control is determined
  666. by the class.  The class is either given by a zero-terminated string,
  667. or in the case of many common Windows classes, is given a one word
  668. code to save space and speed processing - in this case, the ordinal
  669. number will be a WORD in length, but only the lower byte will be
  670. used.  Because UNICODE allows 0x8000 as a legal character, the
  671. ordinal classes are prefaced with a of 0xFFFF, similar to the ordinal
  672. Type and Name fields.  The one byte classes are listed here:
  673.  
  674.     #define    BUTTON              0x80
  675.     #define    EDIT                0x81
  676.     #define    STATIC              0x82
  677.     #define    LISTBOX             0x83
  678.     #define    SCROLLBAR           0x84
  679.     #define    COMBOBOX            0x85
  680.     
  681. The lExtendedStyle DWORD is used to specify the extended style flags
  682. to be used for this control.  The extended style flags are placed at
  683. the end of the CONTROL (or other control statements) statement
  684. following the coordinates
  685.  
  686. The extra information at the end of the control data structure is
  687. currently not used, but is intended for extra information that may be
  688. needed for menu items in the future.  Usually it is zero length.
  689.  
  690. The various statements used in a dialog script are all mapped to
  691. these classes along with certain modifying styles.  The values for
  692. these styles can be found in WINDOWS.H.  All dialog controls have the
  693. default styles of WS_CHILD and WS_VISIBLE.  A list of the default
  694. styles used to make the script statements follows:
  695.  
  696.     Statement       Default Class  Default Styles
  697.     CONTROL         None           WS_CHILD|WS_VISIBLE
  698.     LTEXT           STATIC         ES_LEFT
  699.     RTEXT           STATIC         ES_RIGHT
  700.     CTEXT           STATIC         ES_CENTER
  701.     LISTBOX         LISTBOX        WS_BORDER | LBS_NOTIFY
  702.     CHECKBOX        BUTTON         BS_CHECKBOX | WS_TABSTOP
  703.     PUSHBUTTON      BUTTON         BS_PUSHBUTTON | WS_TABSTOP
  704.     GROUPBOX        BUTTON         BS_GROUPBOX
  705.     DEFPUSHBUTTON   BUTTON         BS_DEFPUSHBUTTON | WS_TABSTOP
  706.     RADIOBUTTON     BUTTON         BS_RADIOBUTTON
  707.     AUTOCHECKBOX    BUTTON         BS_AUTOCHECKBOX
  708.     AUTO3STATE      BUTTON         BS_AUTO3STATE
  709.     AUTORADIOBUTTON BUTTON         BS_AUTORADIOBUTTON
  710.     PUSHBOX         BUTTON         BS_PUSHBOX
  711.     STATE3          BUTTON         BS_3STATE
  712.     EDITTEXT        EDIT           ES_LEFT|WS_BORDER|WS_TABSTOP
  713.     COMBOBOX        COMBOBOX       None
  714.     ICON            STATIC         SS_ICON
  715.     SCROLLBAR       SCROLLBAR      None
  716.     
  717. The control text is stored in the `Name or Ordinal' format described
  718. in detail above.
  719.  
  720. 4.5 Cursor Resources
  721.  
  722. Cursor resources are very much like icon resources.  They are formed
  723. in groups with the components preceding the header.  This header also
  724. employs a fixed-length component index that allows random access of
  725. the individual components.  The structure of the cursor header is as
  726. follows:
  727.  
  728.     [Resource header (type = 12)]
  729.     
  730. struct CursorHeader {
  731.   WORD   wReserved;          // Currently zero
  732.   WORD   wType;              // 2 for cursors
  733.   WORD   cwCount;            // Number of components
  734.   WORD   padding;            // filler for DWORD alignment
  735.   };
  736.     
  737. The next portion is repeated for each component resource, and starts
  738. on a DWORD boundary.
  739.  
  740. struct ResourceDirectory {
  741.   WORD   wWidth;
  742.   WORD   wHeight;
  743.   WORD   wPlanes;
  744.   WORD   wBitCount;
  745.   DWORD  lBytesInRes;
  746.   WORD   wNameOrdinal;       // Points to component
  747.   WORD   padding;            // filler for DWORD alignment
  748.   };
  749.     
  750. Each cursor component is also similar to each icon component.  There
  751. is, however, one significant difference between the two:  cursors
  752. have the concept of a `hotspot' where icons do not.  Here is the
  753. component structure:
  754.  
  755.     [Resource header (Type = 1)]
  756.     
  757. struct CursorComponent {
  758.   short  xHotspot;
  759.   short  yHotspot;
  760.   }
  761.     [Monochrome XOR mask]
  762.     [Monochrome AND mask]
  763.     
  764. These masks are bitmaps copied from the .CUR file.  The main
  765. difference from icons in this regard is that cursors do not have
  766. color DIBs used for XOR masks like cursors.  Although the bitmaps are
  767. monochrome and do not have DIB headers or color tables, the bits are
  768. still in DIB format with respect to alignment and direction.  See the
  769. SDK Reference for more information on DIB formats.
  770.  
  771. 4.6 Bitmap Resources
  772.  
  773. Windows 32 can read two types of device-independent bitmaps.  The
  774. normal type of DIB is the Windows 3.0 DIB format.  The other type of
  775. DIB is that used for OS/2 versions 1.1 and 1.2.  The bitmap resource
  776. consists of a single device-independent bitmap and accordingly, this
  777. DIB can be of either format.  The two DIBs are distinguished by their
  778. header structures.  They both have the size of their respective
  779. structures as the first DWORD in the header.  Both these structures
  780. are documented in the Windows SDK Reference Version 3.0 volume 2,
  781. section 7.  The header structure for the normal DIB is
  782. BITMAPINFOHEADER while the OS/2 DIB header is called
  783. BITMAPCOREHEADER.  The correct size (as a DWORD) must be in the first
  784. entry of the structure.
  785.  
  786.     [Normal resource header (type = 2)]
  787.     
  788.     [BITMAPINFOHEADER or BITMAPCOREHEADER]
  789.     [Color table if not 24 bits per pixel]
  790.     [Packed-pixel bitmap]
  791.     
  792. Note that the color table is optional.  All but 24 bit color bitmaps
  793. have a color table attached next.  This table's length can be
  794. computed by 2#BitsPerPixel * 3 bytes for OS/2 bitmaps or
  795. 2#BitsPerPixel * 4 bytes for Windows bitmaps.  The bitmap image data
  796. is placed immediately following the color table.
  797.  
  798. Note that the BItmap file has an unaligned header structure
  799. (BITMAPFILEHEADER structure).  This header is not, however, stored in
  800. the resource file, as it serves only to identify the type of file
  801. (DIB or DDB)
  802.  
  803. 4.7 Font and Font Directory Resources
  804.  
  805. Font resources are different from the other types of resources in
  806. that they are not added to the resources of a specific application
  807. program.  Font resources are added to .EXE files that are renamed to
  808. be .FON files.  These files are libraries as opposed to applications.
  809.  
  810. Font resources use a resource group structure.  Individual fonts are
  811. the components of a font group.  Each component is defined by a FONT
  812. statement in the .RC file.  The group header follows all components
  813. and contains all information necessary to access a specific font.
  814. The format of a font component resource is as follows:
  815.  
  816.     [Normal resource header (type = 8)]
  817.     
  818.     [Complete contents of the .FNT file follow as the resource body -
  819.     - See the Windows SDK Reference for the format of the .FNT file]
  820.     
  821. The group header for the fonts is normally last in the .RES file.
  822. Note that unlike cursor and icon groups, the font group need not be
  823. contiguous in the .RES file.  Font declarations may be placed in the
  824. .RC file mixed with other resource declarations.  The group header is
  825. added automatically by RC at the end of the .RES file.  Programs
  826. generating .RES files must add the FONTDIR entry manually.  The group
  827. header has the following structure:
  828.  
  829.     [Normal resource header (type = 7)]
  830.     
  831.     WORD NumberOfFonts; // Total number in .RES file
  832.     
  833. The remaining data is repeated for every font in the .RES file.
  834.  
  835.     
  836. WORD fontOrdinal;
  837. struct FontDirEntry {
  838.   WORD   dfVersion;
  839.   DWORD  dfSize;
  840.   char   dfCopyright[60];
  841.   WORD   dfType;
  842.   WORD   dfPoints;
  843.   WORD   dfVertRes;
  844.   WORD   dfHorizRes;
  845.   WORD   dfAscent;
  846.   WORD   dfInternalLeading;
  847.   WORD   dfExternalLeading;
  848.   BYTE   dfItalic;
  849.   BYTE   dfUnderline;
  850.   BYTE   dfStrikeOut;
  851.   WORD   dfWeight;
  852.   BYTE   dfCharSet;
  853.   WORD   dfPixWidth;
  854.   WORD   dfPixHeight;
  855.   BYTE   dfPitchAndFamily;
  856.   WORD   dfAvgWidth;
  857.   WORD   dfMaxWidth;
  858.   BYTE   dfFirstChar;
  859.   BYTE   dfLastChar;
  860.   BYTE   dfDefaultChar;
  861.   BYTE   dfBreakChar;
  862.   WORD   dfWidthBytes;
  863.   DWORD  dfDevice;
  864.   DWORD  dfFace;
  865.   DWORD  dfReserved;
  866.   char   szDeviceName[];
  867.   char   szFaceName[];
  868.   };
  869.     
  870. 4.8 String Table Resources
  871.  
  872. These tables are constructed in blocks of 16 strings.  The
  873. organization of these blocks of 16 is determined by the IDs given to
  874. the various strings.  The lowest four bits of the ID determine a
  875. string's position in the block.  The upper twelve bits determine
  876. which block the string is in.  Each block of 16 strings is stored as
  877. one resource entry.  Each string or error table resource block is
  878. stored as follows:
  879.  
  880.     [Normal resource header (type = 6 for strings)]
  881.     
  882.     [Block of 16 strings.  The strings are Pascal style with a WORD
  883.     length preceding the string.  16 strings are always written, even
  884.     if not all slots are full.  Any slots in the block with no string
  885.     have a zero WORD for the length.]
  886.     
  887. It is important to note that the various blocks need not be written
  888. out in numerical order in the resource file.  Each block is assigned
  889. an ordinal ID.  This ID is the high 12 bits of the string IDs in the
  890. block plus one (ordinal IDs can't be zero).  The blocks are written
  891. to the .RES file in the order the blocks are encountered in the .RC
  892. file, while the CVTRES utility will cause them to become ordered in
  893. the COFF object, and hence the image file.
  894.  
  895. 4.9 Accelerator Table Resources
  896.  
  897. An accelerator table is stored as a single resource.  Multiple
  898. accelerator tables are also allowed.  The format of an accelerator
  899. table is very simple.  No header for the table is used.  Each entry
  900. in the table has a single five-byte entry.  The last entry in the
  901. table has its flag word's high bit set (fFlags |= 0x8000).  Since all
  902. entries are fixed length, random access can be done because the
  903. number of elements in the table can be computed by dividing the
  904. length of the resource by eight.  Here is the structure of the table
  905. entries:
  906.  
  907.     [Normal resource header (type = 9)]
  908.     
  909. The following structure is repeated for all accelerator table
  910. entries.
  911.  
  912. struct AccelTableEntry {
  913.   WORD   fFlags;
  914.   WORD   wAscii;
  915.   WORD   wId;
  916.   WORD   padding;
  917.   };
  918.     
  919. 4.10 User Defined Resources and RCDATA
  920.  
  921. RC allows the programmer to include resources not defined in Windows.
  922. The user may choose a name not defined as a standard type and use it
  923. to include data that is to be used as a resource.  This data may be
  924. taken from an external file or may be placed between BEGIN and END
  925. statements.  As an option, the programmer can define the type as
  926. RCDATA with the same results.
  927.  
  928. As might be imagined, the format of this resource is very simple
  929. because the resource compiler knows nothing about the logical
  930. structure of the data.  Here is the organization:
  931.  
  932.     [Normal resource header (type = 10 for RCDATA, named types
  933.     represent user-defined types)]
  934.     
  935.     [The data from the BEGIN ...  END or from the external file is
  936.     included without translation into the .RES file]
  937.     
  938. 4.11 Name Table and Error Table Resources
  939.  
  940. Name tables and error resources are no longer supported in the
  941. Windows binary resource file format.
  942.  
  943. 4.12 Version Resources.
  944.  
  945. Version resources specify information that can be used by setup
  946. programs to discover which of several versions of a program or
  947. dynamic link library to install into the system.  There is also a set
  948. of api's to query the version resources.  There are three major types
  949. of information stored in version resources:  the main information in
  950. a VS_FIXEDFILEINFO structure, Language information data in a variable
  951. file information structure (VarFileInfo), and user defined string
  952. information in StringFileInfo structures.  For Windows 32, the
  953. strings within the version information resource is stored in Unicode,
  954. providing localization of the resoruces.  Each block of information
  955. is dword aligned.
  956.  
  957. The structure of a version resource is depicted by the
  958. VS_VERSION_INFO structure.
  959.  
  960. VS_VERSION_INFO {
  961.     WORD wLength;             /* Length of the version resource */
  962.     WORD wValueLength;        /* Length of the value field for this block */
  963.     WORD wType;               /* type of information:  1==string, 0==binary */
  964.     WCHAR szKey[];            /* Unicode string KEY field */
  965.     [WORD Padding1;]          /* possible word of padding */
  966.     VS_FIXEDFILEINFO Value;   /* Fixed File Info Structure */
  967.     BYTE Children[];          /* position of VarFileInfo or StringFileInfo data */
  968. };
  969.  
  970. The Fixed File Info structure contains basic information about the
  971. version, including version numbers for the product and file, and type
  972. of the file.
  973.  
  974. typedef struct tagVS_FIXEDFILEINFO {
  975.     DWORD dwSignature;        /* signature - always 0xfeef04bd */
  976.     DWORD dwStrucVersion;          /* structure version - currently 0 */
  977.     DWORD dwFileVersionMS;    /* Most Significant file version dword */
  978.     DWORD dwFileVersionLS;    /* Least Significant file version dword */
  979.     DWORD dwProductVersionMS; /* Most Significant product version */
  980.     DWORD dwProductVersionLS; /* Least Significant product version */
  981.     DWORD dwFileFlagMask;          /* file flag mask */
  982.     DWORD dwFileFlags;        /*  debug/retail/prerelease/... */
  983.     DWORD dwFileOS;      /* OS type.  Will always be Windows32 value */
  984.     DWORD dwFileType;         /* Type of file (dll/exe/drv/... )*/
  985.     DWORD dwFileSubtype;      /* file subtype */
  986.     DWORD dwFileDateMS;       /* Most Significant part of date */
  987.     DWORD dwFileDateLS;       /* Least Significant part of date */
  988. } VS_FIXEDFILEINFO;
  989.  
  990. The user defined string information is contained within the
  991. StringFileInfo structure, which is a set of two strings:  the key and
  992. the information itself.
  993.  
  994. StringFileInfo {
  995.     WCHAR       szKey[];      /* Unicode "StringFileInfo" */
  996.     [WORD        padding;]    /* possible padding */
  997.     StringTable Children[];
  998. };
  999.  
  1000. StringTable {
  1001.     WCHAR      szKey[];       /* Unicode string denoting the language - 8 bytes */
  1002.     String Children[];        /* array of children String structures */
  1003. }
  1004.  
  1005. String {
  1006.     WCHAR   szKey[];          /* arbitrary Unicode encoded KEY string */
  1007.                          /* note that there is a list of pre-defined keys */
  1008.     [WORD   padding;]              /* possible padding */
  1009.     WCHAR Value[];            /* Unicode-encoded value for KEY */
  1010. } String;
  1011.  
  1012. The variable file info (VarFileInfo) block contains a list of
  1013. languages supported by this version of the application/dll.
  1014.  
  1015. VarFileInfo {
  1016.     WCHAR szKey[];       /* Unicode "VarFileInfo" */
  1017.     [WORD padding;];          /* possible padding */
  1018.     Var        Children[];         /* children array */
  1019. };
  1020.  
  1021. Var {
  1022.     WCHAR szKey[];       /* Unicode "Translation" (or other user key) */
  1023.     [WORD padding;]      /* possible padding */
  1024.     WORD  Value[];       /* one or more values, normally language id's */
  1025. };
  1026.  
  1027. 4.13 Messagetable Resources.
  1028.  
  1029. A message table is a resource that contains formatted text that is
  1030. used to display an error message or messagebox.  It has taken the
  1031. place of the error table resource (which was never used).  The data
  1032. consists of a MESSAGE_RESOURCE_DATA structure, which contains one or
  1033. more MESSAGE_RESOURCE_BLOCKS, which in turn may consist of one or
  1034. more MESSAGE_RESOURCE_ENTRY structures.  The structure is similar to
  1035. that of the STRINGTABLE resource.
  1036.  
  1037. typedef struct _MESSAGE_RESOURCE_DATA {
  1038.     ULONG NumberOfBlocks;
  1039.     MESSAGE_RESOURCE_BLOCK Blocks[];
  1040. } MESSAGE_RESOURCE_DATA, *PMESSAGE_RESOURCE_DATA;
  1041.  
  1042. typedef struct _MESSAGE_RESOURCE_BLOCK {
  1043.     ULONG LowId;
  1044.     ULONG HighId;
  1045.     ULONG OffsetToEntries;
  1046. } MESSAGE_RESOURCE_BLOCK, *PMESSAGE_RESOURCE_BLOCK;
  1047.  
  1048. typedef struct _MESSAGE_RESOURCE_ENTRY {
  1049.     USHORT Length;
  1050.     USHORT Flags;
  1051.     UCHAR Text[];
  1052. } MESSAGE_RESOURCE_ENTRY, *PMESSAGE_RESOURCE_ENTRY;
  1053.